/*  
  -- The Lime II Project -- 

  A tuplespaces-based middleware for coordinating agents and mobile hosts.
  Copyright (C) 2005.
  Gian Pietro Picco, Amy L. Murphy, Lorenzo Bellini.

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
  Lesser General Public License for more details.

  You should have received this copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 
*/

package lime2;
import lights.interfaces.*;

/**
 * LimeTuples return data to application programmmers. They are the <i>output</i> of the in, read, etc.. methods of 
 * LimeTupleSpace. Programmers cannot create new LimeTuples: they can extract all the internal information from the 
 * ones returned by the Lime system (TupleID included). 
 * 
 * @author Gian Pietro Picco
 * @author Amy Murphy
 * @author Lorenzo Bellini
 */

public class LimeTuple extends LimeWrapper 
{
 /**
  * Constructor method. Private.
  * 
  * @param w LimeWrapper
  */	
 private LimeTuple(LimeWrapper w)
 { 
  super(w.id, w.cur, w.dest, w.tuple);	
 }
	
 /**
  * Constructor method. Package-visible.
  * 
  * @param id the TupleID
  * @param cur the current Location 
  * @param dest the destination Location 
  * @param tuple the encapsulated tuple
  */
 public LimeTuple(TupleID id, Location cur, Location dest, ITuple tuple) 
 {
  super(id, cur, dest, tuple); 
 }

 /**
  * Returns the TupleID field of this LimeTuple.
  * 
  * @return TupleID
  */
 public TupleID getID() 
 { 
  return id; 
 }

 /**
  * Returns the current Location field of this LimeTuple.
  * 
  * @return Location
  */
 public Location getCurrent() 
 { 
  return cur; 
 }

 /**
  * Returns the destination Location field of this LimeTuple.
  * 
  * @return Location
  */
 public Location getDestination() 
 { 
  return dest; 
 }

 /**
  * Returns the wrapped ITuple of this LimeTuple.
  * 
  * @return encapsulated ITuple
  */
 public ITuple getTuple() 
 { 
  return tuple; 
 }
 
 /** 
  * Converts a LimeTuple into a "limified" ITuple. 
  * In a limified tuple, aka flattened (or flat) tuple, the first field is the TupleID, second is the current
  * Location, third is the destination Location and the remaining fields are the contents of the original tuple. 
  * The ITuple returned is a shallow copy of the ITuple contained in the LimeTuple.
  * 
  * @return "limified" ITuple
  */
 ITuple limify()
 {
  return this.limifyWrapper();	
 }
 
 /** 
  * Converts a "limified" (flattened) ITuple into a LimeTuple. 
  * If any of the fields are not of the proper type, (e.g., first field is TupleID, second is Location, and third is 
  * Location), <code>null</code> is returned. The ITuple within the returned LimeTuple is a shallow copy of the tuple
  * passed as a parameter.
  * 
  * @param flat the "limified" ITuple
  * @return LimeTuple the corresponding LimeTuple
  */ 
 static LimeTuple delimify(ITuple flat)
 {
  LimeWrapper w = delimifyWrapper(flat);
  if (w == null) return null; else return new LimeTuple(w);	
 }
 
 /**
  * toString method.
  * 
  * @return concise textual representation of this LimeTuple
  */
 public String toString() 
 {
  return "[LimeTuple]" +
         " tid="  + (id == null ? "null" : id.toString()) + 
         " cur="  + (cur == null ? "null" : cur.toString()) + 
         " dest=" + (dest == null ? "null" : dest.toString()) +
         " tup="  + (tuple == null ? "null" : tuple.toString());
 }

}
